<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Negative Binomial Distribution</title>
<link rel="stylesheet" href="../../../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Math Toolkit 4.2.0">
<link rel="up" href="../dists.html" title="Distributions">
<link rel="prev" href="lognormal_dist.html" title="Log Normal Distribution">
<link rel="next" href="nc_beta_dist.html" title="Noncentral Beta Distribution">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="lognormal_dist.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="nc_beta_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist"></a><a class="link" href="negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
        Binomial Distribution</a>
</h4></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
          <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Chapter 22. Policies: Controlling Precision, Error Handling etc">Policy</a>   <span class="special">=</span> <a class="link" href="../../pol_ref/pol_ref_ref.html" title="Policy Class Reference">policies::policy&lt;&gt;</a> <span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">negative_binomial_distribution</span><span class="special">;</span>

<span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">negative_binomial</span><span class="special">;</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Chapter 22. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">negative_binomial_distribution</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
   <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
   <span class="keyword">typedef</span> <span class="identifier">Policy</span>   <span class="identifier">policy_type</span><span class="special">;</span>
   <span class="comment">// Constructor from successes and success_fraction:</span>
   <span class="identifier">negative_binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span>

   <span class="comment">// Parameter accessors:</span>
   <span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
   <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>

   <span class="comment">// Bounds on success fraction:</span>
   <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
      <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
      <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
      <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// alpha</span>
   <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
      <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
      <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
      <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// alpha</span>

   <span class="comment">// Estimate min/max number of trials:</span>
   <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span>
      <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span>     <span class="comment">// Number of failures.</span>
      <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span>     <span class="comment">// Success fraction.</span>
      <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// Probability threshold alpha.</span>
   <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span>
      <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span>     <span class="comment">// Number of failures.</span>
      <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span>     <span class="comment">// Success fraction.</span>
      <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// Probability threshold alpha.</span>
<span class="special">};</span>

<span class="special">}}</span> <span class="comment">// namespaces</span>
</pre>
<p>
          The class type <code class="computeroutput"><span class="identifier">negative_binomial_distribution</span></code>
          represents a <a href="http://en.wikipedia.org/wiki/Negative_binomial_distribution" target="_top">negative_binomial
          distribution</a>: it is used when there are exactly two mutually exclusive
          outcomes of a <a href="http://en.wikipedia.org/wiki/Bernoulli_trial" target="_top">Bernoulli
          trial</a>: these outcomes are labelled "success" and "failure".
        </p>
<p>
          For k + r Bernoulli trials each with success fraction p, the negative_binomial
          distribution gives the probability of observing k failures and r successes
          with success on the last trial. The negative_binomial distribution assumes
          that success_fraction p is fixed for all (k + r) trials.
        </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            The random variable for the negative binomial distribution is the number
            of trials, (the number of successes is a fixed property of the distribution)
            whereas for the binomial, the random variable is the number of successes,
            for a fixed number of trials.
          </p></td></tr>
</table></div>
<p>
          It has the PDF:
        </p>
<div class="blockquote"><blockquote class="blockquote"><p>
            <span class="inlinemediaobject"><img src="../../../../equations/neg_binomial_ref.svg"></span>

          </p></blockquote></div>
<p>
          The following graph illustrate how the PDF varies as the success fraction
          <span class="emphasis"><em>p</em></span> changes:
        </p>
<div class="blockquote"><blockquote class="blockquote"><p>
            <span class="inlinemediaobject"><img src="../../../../graphs/negative_binomial_pdf_1.svg" align="middle"></span>

          </p></blockquote></div>
<p>
          Alternatively, this graph shows how the shape of the PDF varies as the
          number of successes changes:
        </p>
<div class="blockquote"><blockquote class="blockquote"><p>
            <span class="inlinemediaobject"><img src="../../../../graphs/negative_binomial_pdf_2.svg" align="middle"></span>

          </p></blockquote></div>
<h5>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h0"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.related_distributions"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.related_distributions">Related
          Distributions</a>
        </h5>
<p>
          The name negative binomial distribution is reserved by some to the case
          where the successes parameter r is an integer. This integer version is
          also called the <a href="http://mathworld.wolfram.com/PascalDistribution.html" target="_top">Pascal
          distribution</a>.
        </p>
<p>
          This implementation uses real numbers for the computation throughout (because
          it uses the <span class="bold"><strong>real-valued</strong></span> incomplete beta
          function family of functions). This real-valued version is also called
          the Polya Distribution.
        </p>
<p>
          The Poisson distribution is a generalization of the Pascal distribution,
          where the success parameter r is an integer: to obtain the Pascal distribution
          you must ensure that an integer value is provided for r, and take integer
          values (floor or ceiling) from functions that return a number of successes.
        </p>
<p>
          For large values of r (successes), the negative binomial distribution converges
          to the Poisson distribution.
        </p>
<p>
          The geometric distribution is a special case where the successes parameter
          r = 1, so only a first and only success is required. geometric(p) = negative_binomial(1,
          p).
        </p>
<p>
          The Poisson distribution is a special case for large successes
        </p>
<p>
          poisson(λ) = lim <sub>r → ∞</sub> negative_binomial(r, r / (λ + r)))
        </p>
<div class="caution"><table border="0" summary="Caution">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top">
<p>
            The Negative Binomial distribution is a discrete distribution: internally,
            functions like the <code class="computeroutput"><span class="identifier">cdf</span></code>
            and <code class="computeroutput"><span class="identifier">pdf</span></code> are treated "as
            if" they are continuous functions, but in reality the results returned
            from these functions only have meaning if an integer value is provided
            for the random variate argument.
          </p>
<p>
            The quantile function will by default return an integer result that has
            been <span class="emphasis"><em>rounded outwards</em></span>. That is to say lower quantiles
            (where the probability is less than 0.5) are rounded downward, and upper
            quantiles (where the probability is greater than 0.5) are rounded upwards.
            This behaviour ensures that if an X% quantile is requested, then <span class="emphasis"><em>at
            least</em></span> the requested coverage will be present in the central
            region, and <span class="emphasis"><em>no more than</em></span> the requested coverage
            will be present in the tails.
          </p>
<p>
            This behaviour can be changed so that the quantile functions are rounded
            differently, or even return a real-valued result using <a class="link" href="../../pol_overview.html" title="Policy Overview">Policies</a>.
            It is strongly recommended that you read the tutorial <a class="link" href="../../pol_tutorial/understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
            Quantiles of Discrete Distributions</a> before using the quantile
            function on the Negative Binomial distribution. The <a class="link" href="../../pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
            docs</a> describe how to change the rounding policy for these distributions.
          </p>
</td></tr>
</table></div>
<h5>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h1"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.member_functions"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.member_functions">Member
          Functions</a>
        </h5>
<h6>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h2"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.construct"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.construct">Construct</a>
        </h6>
<pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span>
</pre>
<p>
          Constructor: <span class="emphasis"><em>r</em></span> is the total number of successes,
          <span class="emphasis"><em>p</em></span> is the probability of success of a single trial.
        </p>
<p>
          Requires: <code class="computeroutput"><span class="identifier">r</span> <span class="special">&gt;</span>
          <span class="number">0</span></code> and <code class="computeroutput"><span class="number">0</span>
          <span class="special">&lt;=</span> <span class="identifier">p</span>
          <span class="special">&lt;=</span> <span class="number">1</span></code>.
        </p>
<h6>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h3"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.accessors"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.accessors">Accessors</a>
        </h6>
<pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="comment">// successes / trials (0 &lt;= p &lt;= 1)</span>
</pre>
<p>
          Returns the parameter <span class="emphasis"><em>p</em></span> from which this distribution
          was constructed.
        </p>
<pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="comment">// required successes (r &gt; 0)</span>
</pre>
<p>
          Returns the parameter <span class="emphasis"><em>r</em></span> from which this distribution
          was constructed.
        </p>
<p>
          The best method of calculation for the following functions is disputed:
          see <a class="link" href="binomial_dist.html" title="Binomial Distribution">Binomial
          Distribution</a> for more discussion.
        </p>
<h6>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h4"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.lower_bound_on_parameter_p"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.lower_bound_on_parameter_p">Lower
          Bound on Parameter p</a>
        </h6>
<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
  <span class="identifier">RealType</span> <span class="identifier">failures</span><span class="special">,</span>
  <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
  <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">)</span> <span class="comment">// (0 &lt;= alpha &lt;= 1), 0.05 equivalent to 95% confidence.</span>
</pre>
<p>
          Returns a <span class="bold"><strong>lower bound</strong></span> on the success fraction:
        </p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">failures</span></dt>
<dd><p>
                The total number of failures before the <span class="emphasis"><em>r</em></span>th
                success.
              </p></dd>
<dt><span class="term">successes</span></dt>
<dd><p>
                The number of successes required.
              </p></dd>
<dt><span class="term">alpha</span></dt>
<dd><p>
                The largest acceptable probability that the true value of the success
                fraction is <span class="bold"><strong>less than</strong></span> the value
                returned.
              </p></dd>
</dl>
</div>
<p>
          For example, if you observe <span class="emphasis"><em>k</em></span> failures and <span class="emphasis"><em>r</em></span>
          successes from <span class="emphasis"><em>n</em></span> = k + r trials the best estimate
          for the success fraction is simply <span class="emphasis"><em>r/n</em></span>, but if you
          want to be 95% sure that the true value is <span class="bold"><strong>greater
          than</strong></span> some value, <span class="emphasis"><em>p<sub>min</sub></em></span>, then:
        </p>
<pre class="programlisting"><span class="identifier">p</span><sub>min</sub> <span class="special">=</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
                    <span class="identifier">failures</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
</pre>
<p>
          <a class="link" href="../../stat_tut/weg/neg_binom_eg/neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">See
          negative binomial confidence interval example.</a>
        </p>
<p>
          This function uses the Clopper-Pearson method of computing the lower bound
          on the success fraction, whilst many texts refer to this method as giving
          an "exact" result in practice it produces an interval that guarantees
          <span class="emphasis"><em>at least</em></span> the coverage required, and may produce pessimistic
          estimates for some combinations of <span class="emphasis"><em>failures</em></span> and <span class="emphasis"><em>successes</em></span>.
          See:
        </p>
<p>
          <a href="http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf" target="_top">Yong
          Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some
          Discrete Distributions. Computational statistics and data analysis, 2005,
          vol. 48, no3, 605-621</a>.
        </p>
<h6>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h5"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.upper_bound_on_parameter_p"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.upper_bound_on_parameter_p">Upper
          Bound on Parameter p</a>
        </h6>
<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
   <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
   <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
   <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// (0 &lt;= alpha &lt;= 1), 0.05 equivalent to 95% confidence.</span>
</pre>
<p>
          Returns an <span class="bold"><strong>upper bound</strong></span> on the success
          fraction:
        </p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">trials</span></dt>
<dd><p>
                The total number of trials conducted.
              </p></dd>
<dt><span class="term">successes</span></dt>
<dd><p>
                The number of successes that occurred.
              </p></dd>
<dt><span class="term">alpha</span></dt>
<dd><p>
                The largest acceptable probability that the true value of the success
                fraction is <span class="bold"><strong>greater than</strong></span> the value
                returned.
              </p></dd>
</dl>
</div>
<p>
          For example, if you observe <span class="emphasis"><em>k</em></span> successes from <span class="emphasis"><em>n</em></span>
          trials the best estimate for the success fraction is simply <span class="emphasis"><em>k/n</em></span>,
          but if you want to be 95% sure that the true value is <span class="bold"><strong>less
          than</strong></span> some value, <span class="emphasis"><em>p<sub>max</sub></em></span>, then:
        </p>
<pre class="programlisting"><span class="identifier">p</span><sub>max</sub> <span class="special">=</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
                    <span class="identifier">r</span><span class="special">,</span> <span class="identifier">k</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
</pre>
<p>
          <a class="link" href="../../stat_tut/weg/neg_binom_eg/neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">See
          negative binomial confidence interval example.</a>
        </p>
<p>
          This function uses the Clopper-Pearson method of computing the lower bound
          on the success fraction, whilst many texts refer to this method as giving
          an "exact" result in practice it produces an interval that guarantees
          <span class="emphasis"><em>at least</em></span> the coverage required, and may produce pessimistic
          estimates for some combinations of <span class="emphasis"><em>failures</em></span> and <span class="emphasis"><em>successes</em></span>.
          See:
        </p>
<p>
          <a href="http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf" target="_top">Yong
          Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some
          Discrete Distributions. Computational statistics and data analysis, 2005,
          vol. 48, no3, 605-621</a>.
        </p>
<h6>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h6"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_e"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_e">Estimating
          Number of Trials to Ensure at Least a Certain Number of Failures</a>
        </h6>
<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span>
   <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span>     <span class="comment">// number of failures.</span>
   <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span>     <span class="comment">// success fraction.</span>
   <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// probability threshold (0.05 equivalent to 95%).</span>
</pre>
<p>
          This functions estimates the number of trials required to achieve a certain
          probability that <span class="bold"><strong>more than k failures will be observed</strong></span>.
        </p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">k</span></dt>
<dd><p>
                The target number of failures to be observed.
              </p></dd>
<dt><span class="term">p</span></dt>
<dd><p>
                The probability of <span class="emphasis"><em>success</em></span> for each trial.
              </p></dd>
<dt><span class="term">alpha</span></dt>
<dd><p>
                The maximum acceptable risk that only k failures or fewer will be
                observed.
              </p></dd>
</dl>
</div>
<p>
          For example:
        </p>
<pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
</pre>
<p>
          Returns the smallest number of trials we must conduct to be 95% sure of
          seeing 10 failures that occur with frequency one half.
        </p>
<p>
          <a class="link" href="../../stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html" title="Estimating Sample Sizes for the Negative Binomial.">Worked
          Example.</a>
        </p>
<p>
          This function uses numeric inversion of the negative binomial distribution
          to obtain the result: another interpretation of the result, is that it
          finds the number of trials (success+failures) that will lead to an <span class="emphasis"><em>alpha</em></span>
          probability of observing k failures or fewer.
        </p>
<h6>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h7"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_0"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_0">Estimating
          Number of Trials to Ensure a Maximum Number of Failures or Less</a>
        </h6>
<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span>
   <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span>     <span class="comment">// number of failures.</span>
   <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span>     <span class="comment">// success fraction.</span>
   <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// probability threshold (0.05 equivalent to 95%).</span>
</pre>
<p>
          This functions estimates the maximum number of trials we can conduct and
          achieve a certain probability that <span class="bold"><strong>k failures or
          fewer will be observed</strong></span>.
        </p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">k</span></dt>
<dd><p>
                The maximum number of failures to be observed.
              </p></dd>
<dt><span class="term">p</span></dt>
<dd><p>
                The probability of <span class="emphasis"><em>success</em></span> for each trial.
              </p></dd>
<dt><span class="term">alpha</span></dt>
<dd><p>
                The maximum acceptable <span class="emphasis"><em>risk</em></span> that more than k
                failures will be observed.
              </p></dd>
</dl>
</div>
<p>
          For example:
        </p>
<pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">-</span><span class="number">1.0</span><span class="special">/</span><span class="number">1000000</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
</pre>
<p>
          Returns the largest number of trials we can conduct and still be 95% sure
          of seeing no failures that occur with frequency one in one million.
        </p>
<p>
          This function uses numeric inversion of the negative binomial distribution
          to obtain the result: another interpretation of the result, is that it
          finds the number of trials (success+failures) that will lead to an <span class="emphasis"><em>alpha</em></span>
          probability of observing more than k failures.
        </p>
<h5>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h8"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.non_member_accessors"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.non_member_accessors">Non-member
          Accessors</a>
        </h5>
<p>
          All the <a class="link" href="../nmp.html" title="Non-Member Properties">usual non-member accessor
          functions</a> that are generic to all distributions are supported:
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution Function</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density Function</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile">Quantile</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.hazard">Hazard Function</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.chf">Cumulative Hazard Function</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mean">mean</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.median">median</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mode">mode</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.variance">variance</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.skewness">skewness</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis">kurtosis</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis_excess">kurtosis_excess</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.range">range</a> and <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.support">support</a>.
        </p>
<p>
          However it's worth taking a moment to define what these actually mean in
          the context of this distribution:
        </p>
<div class="table">
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.meaning_of_the_non_member_access"></a><p class="title"><b>Table 5.3. Meaning of the non-member accessors.</b></p>
<div class="table-contents"><table class="table" summary="Meaning of the non-member accessors.">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Function
                  </p>
                </th>
<th>
                  <p>
                    Meaning
                  </p>
                </th>
</tr></thead>
<tbody>
<tr>
<td>
                  <p>
                    <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density
                    Function</a>
                  </p>
                </td>
<td>
                  <p>
                    The probability of obtaining <span class="bold"><strong>exactly k
                    failures</strong></span> from k+r trials with success fraction p.
                    For example:
                  </p>
<pre class="programlisting"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">)</span></pre>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution
                    Function</a>
                  </p>
                </td>
<td>
                  <p>
                    The probability of obtaining <span class="bold"><strong>k failures
                    or fewer</strong></span> from k+r trials with success fraction p and
                    success on the last trial. For example:
                  </p>
<pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">)</span></pre>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.ccdf">Complement of
                    the Cumulative Distribution Function</a>
                  </p>
                </td>
<td>
                  <p>
                    The probability of obtaining <span class="bold"><strong>more than
                    k failures</strong></span> from k+r trials with success fraction p
                    and success on the last trial. For example:
                  </p>
<pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">))</span></pre>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile">Quantile</a>
                  </p>
                </td>
<td>
                  <p>
                    The <span class="bold"><strong>greatest</strong></span> number of failures
                    k expected to be observed from k+r trials with success fraction
                    p, at probability P. Note that the value returned is a real-number,
                    and not an integer. Depending on the use case you may want to
                    take either the floor or ceiling of the real result. For example:
                  </p>
<pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">P</span><span class="special">)</span></pre>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile_c">Quantile
                    from the complement of the probability</a>
                  </p>
                </td>
<td>
                  <p>
                    The <span class="bold"><strong>smallest</strong></span> number of failures
                    k expected to be observed from k+r trials with success fraction
                    p, at probability P. Note that the value returned is a real-number,
                    and not an integer. Depending on the use case you may want to
                    take either the floor or ceiling of the real result. For example:
                  </p>
<pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">P</span><span class="special">))</span></pre>
                </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><h5>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h9"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.accuracy"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.accuracy">Accuracy</a>
        </h5>
<p>
          This distribution is implemented using the incomplete beta functions <a class="link" href="../../sf_beta/ibeta_function.html" title="Incomplete Beta Functions">ibeta</a> and <a class="link" href="../../sf_beta/ibeta_function.html" title="Incomplete Beta Functions">ibetac</a>:
          please refer to these functions for information on accuracy.
        </p>
<h5>
<a name="math_toolkit.dist_ref.dists.negative_binomial_dist.h10"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.negative_binomial_dist.implementation"></a></span><a class="link" href="negative_binomial_dist.html#math_toolkit.dist_ref.dists.negative_binomial_dist.implementation">Implementation</a>
        </h5>
<p>
          In the following table, <span class="emphasis"><em>p</em></span> is the probability that
          any one trial will be successful (the success fraction), <span class="emphasis"><em>r</em></span>
          is the number of successes, <span class="emphasis"><em>k</em></span> is the number of failures,
          <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
        </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Function
                  </p>
                </th>
<th>
                  <p>
                    Implementation Notes
                  </p>
                </th>
</tr></thead>
<tbody>
<tr>
<td>
                  <p>
                    pdf
                  </p>
                </td>
<td>
                  <p>
                    pdf = exp(lgamma(r + k) - lgamma(r) - lgamma(k+1)) * pow(p, r)
                    * pow((1-p), k)
                  </p>
                  <p>
                    Implementation is in terms of <a class="link" href="../../sf_beta/beta_derivative.html" title="Derivative of the Incomplete Beta Function">ibeta_derivative</a>:
                  </p>
                  <p>
                    (p/(r + k)) * ibeta_derivative(r, static_cast&lt;RealType&gt;(k+1),
                    p) The function <a class="link" href="../../sf_beta/beta_derivative.html" title="Derivative of the Incomplete Beta Function">ibeta_derivative</a>
                    is used here, since it has already been optimised for the lowest
                    possible error - indeed this is really just a thin wrapper around
                    part of the internals of the incomplete beta function.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    cdf
                  </p>
                </td>
<td>
                  <p>
                    Using the relation:
                  </p>
                  <p>
                    cdf = I<sub>p</sub>(r, k+1) = ibeta(r, k+1, p)
                  </p>
                  <p>
                    = ibeta(r, static_cast&lt;RealType&gt;(k+1), p)
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    cdf complement
                  </p>
                </td>
<td>
                  <p>
                    Using the relation:
                  </p>
                  <p>
                    1 - cdf = I<sub>p</sub>(k+1, r)
                  </p>
                  <p>
                    = ibetac(r, static_cast&lt;RealType&gt;(k+1), p)
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    quantile
                  </p>
                </td>
<td>
                  <p>
                    ibeta_invb(r, p, P) - 1
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    quantile from the complement
                  </p>
                </td>
<td>
                  <p>
                    ibetac_invb(r, p, Q) -1)
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    mean
                  </p>
                </td>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">r</span><span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">p</span><span class="special">)/</span><span class="identifier">p</span></code>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    variance
                  </p>
                </td>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">r</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">p</span><span class="special">)</span>
                    <span class="special">/</span> <span class="identifier">p</span>
                    <span class="special">*</span> <span class="identifier">p</span></code>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    mode
                  </p>
                </td>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">floor</span><span class="special">((</span><span class="identifier">r</span><span class="special">-</span><span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="special">(</span><span class="number">1</span> <span class="special">-</span> <span class="identifier">p</span><span class="special">)/</span><span class="identifier">p</span><span class="special">)</span></code>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    skewness
                  </p>
                </td>
<td>
                  <p>
                    <code class="computeroutput"><span class="special">(</span><span class="number">2</span>
                    <span class="special">-</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span>
                    <span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">r</span> <span class="special">*</span>
                    <span class="special">(</span><span class="number">1</span>
                    <span class="special">-</span> <span class="identifier">p</span><span class="special">))</span></code>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    kurtosis
                  </p>
                </td>
<td>
                  <p>
                    <code class="computeroutput"><span class="number">6</span> <span class="special">/</span>
                    <span class="identifier">r</span> <span class="special">+</span>
                    <span class="special">(</span><span class="identifier">p</span>
                    <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span>
                    <span class="identifier">r</span> <span class="special">*</span>
                    <span class="special">(</span><span class="number">1</span>
                    <span class="special">-</span> <span class="identifier">p</span>
                    <span class="special">)</span></code>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    kurtosis excess
                  </p>
                </td>
<td>
                  <p>
                    <code class="computeroutput"><span class="number">6</span> <span class="special">/</span>
                    <span class="identifier">r</span> <span class="special">+</span>
                    <span class="special">(</span><span class="identifier">p</span>
                    <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span>
                    <span class="identifier">r</span> <span class="special">*</span>
                    <span class="special">(</span><span class="number">1</span>
                    <span class="special">-</span> <span class="identifier">p</span>
                    <span class="special">)</span> <span class="special">-</span><span class="number">3</span></code>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    parameter estimation member functions
                  </p>
                </td>
<td>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">find_lower_bound_on_p</span></code>
                  </p>
                </td>
<td>
                  <p>
                    ibeta_inv(successes, failures + 1, alpha)
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">find_upper_bound_on_p</span></code>
                  </p>
                </td>
<td>
                  <p>
                    ibetac_inv(successes, failures, alpha) plus see comments in code.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">find_minimum_number_of_trials</span></code>
                  </p>
                </td>
<td>
                  <p>
                    ibeta_inva(k + 1, p, alpha)
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">find_maximum_number_of_trials</span></code>
                  </p>
                </td>
<td>
                  <p>
                    ibetac_inva(k + 1, p, alpha)
                  </p>
                </td>
</tr>
</tbody>
</table></div>
<p>
          Implementation notes:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              The real concept type (that deliberately lacks the Lanczos approximation),
              was found to take several minutes to evaluate some extreme test values,
              so the test has been disabled for this type.
            </li>
<li class="listitem">
              Much greater speed, and perhaps greater accuracy, might be achieved
              for extreme values by using a normal approximation. This is NOT been
              tested or implemented.
            </li>
</ul></div>
</div>
<div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
      Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
      Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
      Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
      Walker and Xiaogang Zhang<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="lognormal_dist.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="nc_beta_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
